UPDATE: this is ready to go. For a preview of the documentation, see https://sethrj.github.io/celeritas/user/usage/input.html and https://sethrj.github.io/celeritas/user/implementation/core-physics/problem-def.html#setting-up-problems . For an example of how the input will be used, see 769fb8b .

To cleanly reuse the same input across all front ends, I've refactored the input into:

• System parameters (GPU, MPI, logger) that have to be set up at the very beginning
• Code to set up Geant4 (for standalone apps only (celer-sim and celer-g4), not applicable to user app/framework integration)
• Problem definition
• Code to load data from Geant4, i.e. setting up what part of Geant4 to pull into Celeritas
• Event files (for standalone apps only)
• Custom hook for adding user-defined processes, user-defined diagnostics, etc. (for framework only).

There's a lot of code changes, but most of it is moving stuff around and adding "adapter" code. There is also a lot of documentation.

Currently the code is "orphaned" i.e. it doesn't do anything useful; the next stage will be to merge the shared params setup code from the three front ends into a single place in celeritas/setup/.

Related to #1556 , I'd like to specify a unified mechanism for creating core params, states, etc. before continuing work on that front. Simultaneously (in light of the Optical work) we've been discussing a "refactored" IO where we specify Celeritas inputs to classes separately from the classes themselves. This ties in with #1204 and #1263 and the unification of RunInput/RunnerInput/SetupOptions.

As a first step, I've defined a new directory and namespace inp where we can move all the "input"/"option" classes into. For now we can hand-roll these in C++ (and adapt them from existing input classes), but I'd like to keep working on celeritas-project/celerpy#4 . We should get some working C++ structs before writing the python code and adapters, but ChatGPT seems able to help here, since it was able to generate this from the new inp::Tuning C++ class:

class Tuning(BaseModel):
    """Set up system/tuning parameters that don't affect physics.

    Defaults:
        - `track_order`: `init_charge` on GPU, `none` on CPU.
    """

    capacity: StateCapacity
    "Per-process state sizes."

    optical_capacity: Optional[StateCapacity] = None
    "Per-process state sizes for *optical* tracking loop."

    num_streams: PositiveInt = 0
    "REMOVE: number of streams."

    device: Optional[Device] = None
    "Optional: activate GPU."

    track_order: Optional[str] = None
    "Track sorting and initialization."

    warm_up: bool = False
    "Perform a no-op step at the beginning to improve timing measurements."

    seed: PositiveInt
    "Random number generator seed."

    environ: Dict[str, str]
    "Environment variables used for program setup/diagnostic."

I used ChatGPT to help with the initial translation of SetupOptions, RunInput, and RunnerInput to the new unified inp::Input class.

Note that for now we will need to restrict the along-step field choices to our built-in ones. I'd like to extend so that we can use more type-safe attributes (e.g. ParticleId) along @hhollenb 's line of thinking.

If this sounds good, I'll add documentation to the manual about how I expect this will be used. Follow-on PRs will:

• create core params from inp data
• support JSON->inp conversion (and output?? maybe instead we should have output of the lower-level data)
• move FooParams::Input, FooParams::Option, FooOptions, etc. into inp structures
• and then continue with refactoring.

Talking this through with @hhollenb I think we'll want to separate "standalone" driver functionality (primary generator definition) from the rest of it.

Goals

There are three categories of input types:

• Exclusive Celeritas inputs such as state size and other diagnostic/tuning parameters. Also some parameters we cannot deduce from Geant4: e.g., sensitive detector attributes.
• Parameters that we want to use to drive Geant4 for celer-g4, or pull from Geant4 if we're not. This would include geometry definition (GDML), EM parameters, active processes, scoring meshes.
• Problem setup options that we cannot directly understand from Geant4 but must be provided directly to lower-level Celeritas objects. In particular, we need to be able to allow users to add custom processes, magnetic fields, etc.

Reduce duplication of CoreParams construction and front end input

Currently celer-sim, celer-g4, and direct framework coupling all have slightly different interfaces. They also all independently construct CoreParams. I want to be able to use all the built-in functionality of Celeritas from any front end.

Reduce duplication of input parameters

Currently for celer-g4, we have (using linear_loss_limit as an example):

JSON/macro → GeantPhysicsOptions → CelerEmPhysicsList → Geant4 → GeantImporter → ImportEmParameters → PhysicsParamsOptions::linear_loss_limit → PhysicsParamsScalars

This is a crazy amount of duplication and hard to keep track of where parameters come from and go. The duplication makes it harder to extend: to add support for region/particle-dependent limits we'd have to change a lot of code.

Unify and refactor input to classes

A data-oriented approach will let us restructure e.g. Sim/TrackInit params, as well as Physics, since the input can be pulled from multiple input structs. It also provides a single location where input structs are defined, rather than scattered throughout the codebase. That will ease the transition to a JSON front end and remove a lot of the assignment of foo.x = bar.x between input classes.

Enable well-defined extension points

The current generic SetupOptions only gives one way to extend the actions: make_along_step. Instead we want to be able to extend actions, along-step, physics processes, etc.